Aminet 30/Aminet 30 (1999)(Schatztruhe)[!][Apr 1999].iso/Aminet/dev/misc/WHDLoad_dev.lha/WHDLoad/Patcher1.05dev.lha/Patcher1.05/PatcherDeveloper.readme

Text File | 1998-01-17 | 12KB | 284 lines

Programmers description:
MAKECOMPTAB gives the differences in a way which is used in a module.
Options are:
MAKECOMPTAB ?    - gives a short description
MAKECOMPTAB "original" "patchedfile" {"tableoutput"}
    - compares original with patched file and writes the differences
      to tableoutput, if specified.
Commandline for Directoryopus is: Makecomptab "{fu}" "{d}{ou}" "RAM:table_{o}"
It compares the selected file in the source window with the equal named
file in the destination window and writes the table of differences to RAM:.

If you dont understand the following text, please look at the examples
for modules. I find it easier to see an example and a description
together cause it is complicate to explain some things here under-
standable.

Structure of a module for The Patcher:
    MOVEQ.L    #20,D0        ;four fillbytes (reserved!)
    RTS
    DC.L    TABLE        ;pointer on the tagarray
    DC.B    'PTCH'        ;for recognizing module
    ...
TABLE    {TAGS}
    DC.L    TAG_DONE
    ...


Supported tags:

TAG_DONE        = $00000000
Finishes the tagtable.

PCH_ADAPTOR        = $80004451
    DC.L    {^yourname}
Name of the people which did the fixing work :). Maximally 2 lines of
appr. 40 characters, each line finished by $A and the text ended with $0.
This tag is necessary.

PCH_NAME        = $80004458
    DC.L    {^parametername}
Name of the game, max. 1 line of appr. 40 characters. The filename of the
parameter itself is meaningless. This tag is necessary.

PCH_FILECOUNT        = $80004450
    DC.L    {#filecount}
Number of cycles to execute, mostly equal to the total number of the files
to modify or save (all disks added). This tag is necessary.

PCH_FILENAME        = $80004454
    DC.L    {^array of ^filenames}
Points on an array of the pointers on the filenames (with path).

PCH_DISKNAME        = $80004452
    DC.L    {^array of ^disknames}
Points on an array of the pointers on the disknames (without : !!).

PCH_CHANGES        = $80004456
    DC.L    {^array of ^changestables}
Points on an array of the pointers on the changestables obtained by
MAKECOMPTAB.

PCH_CHECKDISK        = $80004453
    DC.L    {^array of ^ckeckroutines}
Points on an array of the pointers on the customcheckroutines. This tag is
only necessary if you want to recognize a nonstandard disk (but i prefer to
recognize the disk in the PCH_SPECIAL-routine).

PCH_MINVERSION        = $80004459
    DC.L    {^versionstring}
If your parameter requires a feature of a higher version of THE PATCHER,
you can set a versionstring. Useful eg for commandline-parameters.
Stringformat: DC.B    'V1.03',0

PCH_PROCESSING        = $80004457
    DC.L    {^array of ^processingroutines}
Points on an array of the pointers on specialroutines. Such a specialroutine
can be a decryptroutine. For more information look at the parameter
of populous.

PCH_LOADOFFSET        = $8000445A
    DC.L    {^array of offsets}
Points on an array of offsets of the loaded file, this means the file
will be appended on that space. Required for changing the startup-sequence
if you want to insert a line at the top (for ex. FIRST{Return}, then you
have an offset of 6).

PCH_APPENDSPACE        = $8000445E
    DC.L    {^array of space}
Points on an array of space appended on the loaded file, this means the space
will be appended on that file. Required for changing the startup-sequence
if you want to insert a line at the bottom (for ex. LAST{Return}, then you
have an space of 5).

PCH_STATE        = $8000445C
    DC.L    {^array of ^statetexts}
Points on an array of pointers on statetexts. Required for nonstandard
disks, when you need a formatconversion and will have to read the original
disk so that you have to write "Please insert your original writeprotected
disk." instead of "Please insert a copy of your disk and wait for
processing.".

PCH_STATE2        = $8000445D
    DC.L    {^array of ^statetexts2}
Points on an array of pointers on statetexts. Required for nonstandard
disks, when you need a formatconversion and will have to write to the
destination disk so that you must write "Please insert your destination
disk." instead of "Please insert a copy of your disk and wait for
processing.".

PCH_INIT        = $8000445B
    DC.L    {^initialisation routine}
If a parameter must be initialized, you can do that here.

PCH_SPECIAL        = $80004455
    DC.L    {^array of ^specialroutines}
Here could be routines for loading data of a nonstandard disk.

PCH_SAVEPGM        = $80004464
    DC.L    {^array of ^specialroutines}
Here could be routines for saving data on a nonstandard disk.

PCH_SAVEDATA        = $8000445F
    DC.L    {^array of ^datatables}
Needed if you have to save an additional file to disk.

PCH_DATALENGTH        = $80004460
    DC.L    {^array of lengths of data to save}
Needed when a formatconversion is made or you have to save an additional
file on the disk. Or you use it to ensure the correct version of the
game.

PCH_BOOTBLOCK        = $80004461
    DC.L    {^array of ^bootblocks}
Saves the declared bootblock on disk. The Bootblock has to be in chipmemory!

PCH_FINISH        = $80004462
    DC.L    {^finishing routine}
If a parameter has to do some finishing-code (eg freeing self-allocated
memory), you can do that here.

PCH_ERRORINPARAMETER    = $80004463
    DC.L    {^error routine}
If an error occured and a parameter has to do some finishing-code, you can do
that here.


Running:
It clears the area given by PTB_SPACE.
At first it checks if an initroutine (PCH_INIT) is present.
Then it detects the number of cycles (PCH_FILECOUNT).
Now it moves #0,D6.
Now begins the cyclic program:
 It tries to write out the state (PCH_STATE).
 Then it tries to get the diskname (PCH_DISKNAME) and to check for the
 diskvolume.
 Then it would execute a customcheckroutine for the disk (PCH_CHECKDISK).
 Then it gets the filename (PCH_FILENAME).
  If there is a tag for a customroutine (PCH_SPECIAL), it would
  happen the following:
   It accounts the RAM given by PCH_DATALENGTH (obviously in that case it is
   needed). PTB_ADDRESSOFFILE points on that area.
   It doesnt load the file given by the filename, but executes your
   customroutine, which could be a loading routine.
   Now it writes out the save state (PCH_STATE2) if present.
   Then it executes a routine if PCH_PROCESSING is present.
   Then it makes the changes given by PCH_CHANGES.
   Then it will execute the routine given by PCH_SAVEPGM.
   Then it will save the file (only if a filename was given). Cycle ends.
  If there is a tag for saving a bootblock (PCH_BOOTBLOCK),
   it tries to write out the message of PCH_STATE2.
   Then the bootblock will be saved. Cycle ends.
  If there is a tag for saving a file (PCH_SAVEDATA),
   the length of that file will be given by PCH_DATALENGTH.
   It tries to write out the message given by PCH_STATE2.
   Then the file will be saved.
  Otherwise it will execute the following:
   It gets the length of the file.
   Then it tries to detect PCH_LOADOFFSET and PCH_APPENDSPACE and
   evaluates the filelength.
   Then it compares the filelength with the length given by PCH_DATALENGTH
   (if present) and cancels the parameter processing if not equal.
   Then it would account the RAM evaluated and load that file.
   Now it writes out the save state (PCH_STATE2) if present.
   Then it executes a routine if PCH_PROCESSING is present. See also
   the example of Populous.
   Then it makes the changes given by PCH_CHANGES.
   Then it will save the file.
Here ends the cyclic program.
If there is a finishing routine {PCH_FINISH} it will be executed.
Source- and destinationdevice will be closed, if it were opened.
It is impossible to check all correct combinations, so FIRST think about it
and then plan a module. When you give the tag PCH_SAVEDATA and no filename,
an error will occur or the program crashes!

In the routines in the cyclic programexecution D6 gives the actual cycle. Look
at the example of imagergemx.
On all moduleroutines A5 points on the following area:
PTB_DOSBASE        = $0    Base of the dos.library.
PTB_ADDRESSOFFILE    = $4    Points on the filedata.
PTB_INTUITIONBASE    = $8    Base of the intuition.library.
PTB_GFXBASE        = $C    Base of the graphics.library.
PTB_WINDOW        = $10    Points on the structure Window.
PTB_FILENAME        = $14    Points on the filename.
PTB_FULLNAME        = $18    Points on the filename with the volumename.
PTB_FILESIZE        = $1C    Gives the filesize.
PTB_DISKNAME        = $20    Points on the volumename.
PTB_OPENDEVICE        = $24    Points on a routine to open the device
                specified in the CLI. Needed only if you
                have to convert a nonstandard disk.
                D0 = 0    opens for source
                D0 = 1    opens for destination
PTB_DEVICESOURCEPTR    = $28    If you called PTB_OPENDEVICE with D0=0, this
                shows the base of the source device, otherwise
                it is 0.
PTB_DEVICEDESTPTR    = $2C    If you called PTB_OPENDEVICE with D0=1, this
                shows the base of the destination device,
                otherwise it is 0.
PTB_SPACE        = $30    Points on a chipmem-area of $C000 bytes for
                buffering any data (not used in the main
                program).
PTB_FORMATDEST        = $34    Formats a dd-disk in the destination drive,
                when called with D0=0. Returns D0=0 on success.
PTB_REQUEST        = $38    Shows a Ok-Cancel-requester. Two lines of
                text are allowed, given in A0 and A1.
                Returns D0=0 on Ok and -1 on Cancel.
New in version 1.02:
PTB_FSSMSOURCEPTR    = $3C    If PTB_OPENDEVICE was successfully called the
PTB_FSSMDESTPTR        = $40    corresponding PTB_FSSM*PTR points on the
                FileSystemStartupMessage-structure of that
                device.
PTB_INHIBITDRIVE    = $44    Inhibits the source-drive, when called with
                D0=0 and the destination-drive when called
                with D0=1. Returns D0=0 on success.
PTB_ENABLEDRIVE        = $48    Enables the inhibited source-drive when
                called with D0=0 and the destinationdrive when
                called with D0=1. Returns D0=0 on success.

New in version 1.03:
PTB_CRC16        = $4C    Returns in D0 a 16-bit-CRC of an area given by
                a pointer in A0    and a length in D0.

New in version 1.05:
PTB_DISPLAY        = $50    Displays the string in A0 in the messagearea.
                Maximally 2 lines of appr. 40 characters,
                each line finished by $A and the text ended
                with $0. Look at the example of the encounter-
                imager.

You can use all registers in your module, the regs are rescued on
the stack before executing your program.

All routines must return 0 in D0 if all went ok.

The parameters may contain all kind of hunks and memorytypes.

Please dont change the tags itself of a parameter while execution. The
value of the tags and the tables itself may be changed in execution
(see at the example of imagernitro), but AT LEAST ONE cycle before they
are needed, eg you may change stuff for cycle 1 in PCH_INIT, stuff for
cycle 3 in cycle 2 and so on. The only exception from that rule is
PCH_CHANGES which may be changed at any time before use.
If you have to convert a nst-disk to files and you get your filenames from
the disk, you can use 2 spaces for filenames alternating and set the one
which is unused in the current cycle.

Sorry, but all examples can be assembled only with uppercase=lowercase.

Tricks:
If you want to insert a line at the top of the startup-sequence, please
change the startup-sequence once to the destination and once insert only
fillbytes (for ex. @) instead. Then use the true startup-sequence as
patchfile and the dummy one as original with MAKECOMPTAB and you will get
your changestable.

Examples:
parambane - Really easy example of alteration of a file (DOS-game)
parampopulous - to show some abilities of the patcher of altering files
paramcarriercommand - (historical) creates an executable with the data
    of a NONDOS-disk (use now whdload/jst instead of a file if you patch!)
encounter.imager - Basic example for imagers. Use this if you create own ones
nitro.imager - Shows the abilities of The Patcher in (nearly) their entire
    range
wotd.imager - example for multidisk-imaging, sectorized disk